Before continuing, you should read the "Marionet TV Instructions" document. You'll also need a TCP/IP connection to the internet. Lastly, we assume some basic familiarity with HyperCard or SuperCard including the ability to create new stacks or projects; to write simple scripts; and to install and use XCMDs.
In this tutorial, you will create a simple program that sends email messages. You will learn how to begin a session, make a session synchronous (one task at a time), send an email message, check for errors, end a session, and quit Marionet. With the finished program you will be able to subscribe to the Marionet Mailing list where other users of Marionet discuss the product.
After completing this tutorial and exploring the included finished examples, you should have a good understanding of how to develop with Marionet. While these are all simple examples, the process is roughly the same whether you are sending an email message, downloading a file, searching a gopher server, getting the html for a web page, posting a message to a newsgroup, or any number of other tasks you can perform with Marionet.
Constructing the Stack or Project
Depending on whether you are using HyperCard or SuperCard, you'll need to make a new stack or project. A single card with 5 card fields and a card button named "Send" are all that will be required. Below is a screen shot of a HyperCard stack which illustrates how the finished card might look. It is not important to recreate, exactly, the card shown below - just make something similar.
You'll need to use ResEdit or a similar program to install the Marionet XCMD into your stack. In the case of SuperCard, you would use the Import Resources option in SuperEdit to import the XCMD into your project.
Now we'll look at the individual Marionet commands we'll be using for this project.
The BeginSession and EndSession Commands
Before doing anything with Marionet, you must ensure that it is launched and you must have a session id number. A session id identifies a "thread" or "session" in Marionet. Because you can use Marionet asynchronously, the session id is used to identify individual tasks such as downloading a file or sending an email message. A single command, BeginSession, is used to request session ids and to take care of the details of launching Marionet as needed.
The BeginSession command has the following syntax:
Marionet "BeginSession"
The result of this command will contain two lines. The first line will be either OK or ERROR. If the first line is OK then the second line will contain a session id. If the first line is ERROR, then the second line will contain an error message. When you call BeginSession, the Marionet XCMD will automatically check to see if Marionet is running. If Marionet is not running, the XCMD will search your local hard disks for Marionet and launch it.
NOTE: Be aware that BeginSession will launch the first copy of Marionet it finds which may or may not be the trial version (you may have previously downloaded the earlier public beta of Marionet or you may have purchased the full product already). The full product includes an application called Marionet Manager which allows you to specify which copy of Marionet to use, including copies running on workgroup servers that you may be connected to.
Once you have a session id, you'll generally want to save it for future reference, perhaps in a global variable. When you are finished with a session, you'll need to dispose of it — the EndSession command is used for this purpose:
Marionet "EndSession", sessionID
Here is a simple function which begins and ends sessions:
Function ManageSession sessionID
Global gErrorMessage
IF sessionID is empty THEN -- begin a new session
Marionet "BeginSession"
put the result into SessionID
IF line 1 of SessionID is "OK" THEN -- new session, marionet is running
delete line 1 of SessionID -- clean up
ELSE
put line 2 of SessionID into gErrorMessage -- save error message
put empty into SessionID
END IF
ELSE Marionet "EndSession", SessionID -- end the session
Return SessionID
End ManageSession
If ManageSession is not passed a value, it tries to create a new session. If it is successful in creating a session, it returns the session id. If it cannot create a session, it returns empty and the global variable gErrorMessage will contain the error message.
If ManageSession is passed a session id, it ends that session - you would ignore the return value in this case.
The SessionSet Command
Marionet sessions have various properties such as sync (synchronous), name, etc. The SessionSet command is used to set these properties. The syntax for SessionSet is:
For this example, we'll be using a synchronous session (for an example of the scripting required for an asynchronous session, refer to one of the included example programs). Besides the obvious property values for the Sync property (true|false) others are available such as "cursor". We'll be using the cursor property value in this example. The value "cursor" is the same as setting the sync property to true except that it also causes a beachball cursor to spin whenever a command is executing in the session.
Using the ManageSession function above, a handler that created a new synchronous session might look like this:
On mouseUp
Global gSessionID, gErrorMessage
IF gSessionID is empty THEN -- is there already a session available?
put ManageSession() into gSessionID
IF gSessionID is empty THEN -- an error occurred
answer gErrorMessage -- display the error
exit mouseUp -- abort
END IF
Marionet "SessionSet", gSessionID, "sync", "cursor" -- set the sync property
dosomeMarionetcommand....
get ManageSession(gSessionID) -- end the session
put empty into gSessionID
END IF
End mouseUp
The SendMail Command
One of the many internet tasks that Marionet can perform is sending email. The SendMail command is used for this purpose. Marionet also includes a number of commands for managing email - counting messages, downloading messages, deleting messages, etc. which are discussed in the full product's manual.
The braces around the errorVar parameter denote a synchronous parameter. Synchronous parameters are simply variables that will be filled in by Marionet for use after the call is completed. In other words they are a way for Marionet to return values to you in addition to "the result".
In SuperCard, synchronous parameters are declared local variables which are passed by reference. In HyperCard (and other XCMD environments), they are global variables passed as quoted strings. Here are some examples to illustrate:
SuperCard:
on MailSender sessionID, serverName, from, to, messageText
local errorVar
SendMail sessionID, serverName, from, to, messageText, @errorVar
get the result
if line 1 of it is not "OK" then.....
If line 1 of errorVar is not "OK" then....
end MailSender
HyperCard:
on MailSender sessionID, serverName, from, to, messageText
global gErrorVar
SendMail sessionID, serverName, from, to, messageText, "gErrorVar"
get the result
if line 1 of it is not "OK" then.....
If line 1 of gErrorVar is not "OK" then....
end MailSender
The other parameters to SendMail are as follows:
SessionID: a valid session id as discussed previously.
ServerVersion: the name or ip address of your mail server. For example: cts.com
From: your email address. For example: yourName@somewhere.com
ToList: One or more email addresses, separated by commas, to send the message too.
MessageText: The actual message to send. You must include any header information you want included with the message in addition to the actual message text. For example, a subject line:
Subject: the subject of this message
the actual message here
There must be a blank line separating any header information from the actual message. At a minimum, you should always include a subject for the header. A formal discussion of message headers is beyond the scope of this tutorial.
Building on the ManageSession and mouseUp handlers shown previously, here is a script which sends a simple message to a single address (for HyperCard):
On mouseUp
Global gSessionID, gErrorMessage, gErrorVar
IF gSessionID is empty THEN -- is there already a session available?
put ManageSession() into gSessionID
IF gSessionID is empty THEN -- an error occurred
answer gErrorMessage -- display the error
exit mouseUp -- abort
END IF
Marionet "SessionSet", gSessionID, "sync", "cursor" -- set the sync property
put "mail@server" into mailServer
put "myName@mydomain.com" into myAddress
put "theirName@theirdomain.com" into theirAddress
put "Subject: big test" & return & return & "Hello World!" into messageText
ELSE IF (line 1 of gErrorVar) is "ERROR" THEN -- internet error of some sort
answer line 2 of gErrorVar
END IF
get ManageSession(gSessionID) -- end the session
put empty into gSessionID
END IF
End mouseUp
The Quit Command
When it is time to quit your program, it is your responsibility as the developer to quit Marionet. The Quit command syntax is simply:
Marionet "Quit"
Marionet will not quit if the quit command comes from another machine over the network, if the user has configured Marionet not to quit using the Marionet Manager application, or if any sessions are currently active (you can call Marionet "ListSessions" at anytime to get a list of session ids in the result). For these reasons, you don't need to check for errors with the Quit command, just call it and Marionet will Quit if appropriate.
Bringing Everything Together
Ok, you should now have a good overview of how to develop with Marionet and an understanding of the commands we'll be using. It's time to build the Send Mail program.
If you have not already constructed the stack or project discussed at the beginning of this tutorial, now's the time to do it.
First, name the individual fields in the stack or project as follows (reading from the top of the card down):
MailServer
MailAddress
ToAddress
Subject
Message
Now, we'll modify the send mail example script shown previously to refer to those fields (for HyperCard):
On mouseUp
Global gSessionID, gErrorMessage, gErrorVar
IF gSessionID is empty THEN -- is there already a session available?
put ManageSession() into gSessionID
IF gSessionID is empty THEN -- an error occurred
answer gErrorMessage -- display the error
exit mouseUp -- abort
END IF
Marionet "SessionSet", gSessionID, "sync", "cursor" -- set the sync property
put card field "MailServer" into mailServer
put card field "MailAddress" into myAddress
put card field "ToAddress" into theirAddress
put card field "Subject" into subject
put "Subject: " & card field "Subject" into subject
ELSE IF (line 1 of gErrorVar) is "ERROR" THEN -- internet error of some sort
answer line 2 of gErrorVar
END IF
get ManageSession(gSessionID) -- end the session
put empty into gSessionID
END IF
End mouseUp
If you are using SuperCard, modify the above handler so that the ErrorVar parameter is declared as a local and is passed by reference to SendMail as discussed previously. The script should look like this for SuperCard (note the bold face type to indicate the differences):
On mouseUp
Global gSessionID, gErrorMessage
LOCAL errorVar
IF gSessionID is empty THEN -- is there already a session available?
put ManageSession() into gSessionID
IF gSessionID is empty THEN -- an error occurred
answer gErrorMessage -- display the error
exit mouseUp -- abort
END IF
Marionet "SessionSet", gSessionID, "sync", "cursor" -- set the sync property
put card field "MailServer" into mailServer
put card field "MailAddress" into myAddress
put card field "ToAddress" into theirAddress
put card field "Subject" into subject
put "Subject: " & card field "Subject" into subject
ELSE IF (line 1 of errorVar) is "ERROR" THEN -- internet error of some sort
answer line 2 of errorVar
END IF
get ManageSession(gSessionID) -- end the session
put empty into gSessionID
END IF
End mouseUp
Place the mouseUp handler into the Send button in the stack or project. This handler takes care of all the details of launching Marionet, creating a new session, setting the session to synchronous, constructing an email message, sending the message, and terminating the session. It also performs some simple error checking.
Next, take the ManageSession handler shown previously and place it into the stack or; for SuperCard; the window script.
The only thing remaining is to take care of quitting Marionet when your program is quit. In HyperCard, add the following handler to the stack script of your stack:
On closeStack
Marionet "Quit"
pass closeStack
End closeStack
For SuperCard, add the following handler to the script of the window:
On closeWindow
Marionet "Quit"
pass closeWindow
End closeWindow
Try It Out!
Try sending some email to yourself. Enter your mail server name in the Mail Server field. If you don't know the name of the mail server, it's often the same as your domain name from your email address (the part after the @ symbol). Next enter your email address in both of the address fields, a subject in the subject field, and a message in the message field. Then click the send button. Assuming your machine is connected to the internet, the message should be sent to your mail server. Use your normal email program to retrieve it.
If the first test worked, then it's time to try sending a message to someone else — how about us? Allegiant maintains a mailing list to facilitate discussion of Marionet among current users and potential users. It's a great place to ask questions about the product and to learn what others are using it for. To subscribe to the list, address your message to marionet@list.allegiant.com and put the word Subscribe into the SUBJECT line of the message. Leave the body of the message empty. Click the Send button and a short time later a message will arrive in your mail box welcoming you to the mailing list.
Thank-you!
We hope you have enjoyed this introduction to Marionet and that you've found the Trial Version useful. We look forward to your order when you're ready - the How To Order document contains all the needed contact information for placing your order. Thanks again!
P.S. The Marionet 1.1 Trial Version will time-out after 30-days. However, a small number of commands will continue to work. All of the commands used in this Tutorial will continue to work even after the Trial Version has timed-out.
